feat(snippets): guard generated Code-page snippets on result.absent_when - #1584

STACKED — merging lands on docs/router-model-page-pilot (owned by @mattmillerai, PR #1533), NOT main. Do not treat this as ready to merge to the default branch. The generator and every code.yaml exist only on #1533, so this builds on that branch and should land there (or be rebased once #1533 merges).

ELI-5

Google's image and text models can refuse a prompt. When they do, the response has no candidates at all — just a promptFeedback.blockReason saying why. Our generated Quick-start snippets reached straight into result["candidates"][0]..., so a reader who pasted one and tripped a safety filter got a bare KeyError (Python) or a throw on undefined (TypeScript) and never saw the reason. Now the snippets check for that field first and exit with the reason printed.

Description

Adds an opt-in result.absent_when: {path, label} key to the code.yaml spec. When a spec sets it, the Python and TypeScript emitters check that field before reading the result and exit non-zero with the object printed. cURL is unchanged because it never indexes the result.

Generator (.github/scripts/snippets/gen-code-pages.ts):

• Spec.result gains absent_when?: { path: string; label: string }. absent_when.path uses the same dotted syntax as result.path and reuses pathSegments().
• Three emitter helpers next to pyPath/tsPath: pySafeGet (result.get("promptFeedback", {}).get("blockReason")), tsSafeGet (data.promptFeedback?.blockReason) and tsAbsentType (promptFeedback?: { blockReason?: string }). Index segments are rejected with bad absent_when path: index segments unsupported, which keeps each guard a single expression.
• tsResultType now returns the object body rather than a full object type, so the absent_when member can be spliced in alongside it. It has exactly one call site (typescriptSnippet), which re-adds the braces.
• The main loop validates absent_when next to the existing missing required key checks, so a bad spec is reported per-spec and the run carries on instead of throwing.

Specs: the four Google code.yaml (gemini, nano-banana-2, nano-banana-2-lite, nano-banana-pro) set absent_when: {path: promptFeedback.blockReason, label: prompt blocked}. BFL and Ideogram are deliberately untouched: Router converts BFL moderation to a non-2xx error before the body reaches the snippet, and Ideogram has no documented empty-success shape.

The guard keys on blockReason, not on promptFeedback presence, and that distinction is load-bearing: PromptFeedback also carries safetyRatings, so a successful response can legitimately include promptFeedback with no blockReason. Gating on the parent object would abort those.

The one behaviour-changing line, and why it is safe

tsResultType changing its return shape is the only edit that touches existing behaviour; everything else is additive. Two independent things make it safe rather than a presumed regression:

• pathSegments()'s per-part regex is ^([^[]+)((?:\[\d+\])*)$, whose first group requires at least one non-[ character. Segment 0 is therefore always a string key, never an index, so emitting ${segs[0]}: ${t} and letting the caller re-add the braces is total over the reachable input space. I walked the remaining shapes explicitly — a, a[0], a.b, a[0].b.c[0].d — and the new form reproduces the old one on each.
• Empirically: all nine pages regenerate, and the five non-Google code.mdx come back byte-identical. --check proves that independently of the diff.

How has this been tested?

Re-verified from scratch on this branch; every number below is one I measured, not one inherited.

• bun .github/scripts/snippets/gen-code-pages.ts --check --validate (the code-pages:check script): 9 code page(s) fresh, exit 0. Running the writing form and then git status leaves a clean tree, so generation is idempotent.
• bun .github/scripts/snippets/check-provider-schemas.ts --verbose (the repo's other CI job on these paths): 14 models checked, 0 skipped, 0 errors, 262 warnings, exit 0. Every warning is pre-existing and about input/output fields this PR does not touch; none mentions promptFeedback. (The prior count on this branch was 269 — the job reads Google's live discovery document, so the warning total drifts with the provider, not with this diff.)
• The regenerated nano-banana-2 Python snippet, blocked path, with result = {"promptFeedback": {"blockReason": "SAFETY"}} substituted for the client call: exits 1 with prompt blocked: {'blockReason': 'SAFETY'}. The same snippet on a response carrying candidates prints the base64 image and exits 0. Both run on Python 3.9.6 and 3.14.6 — see the deviation below for why the old version matters.
• The bug is real, not assumed: the same blocked response through the pre-change snippet raises KeyError: 'candidates', with no mention of the block reason anywhere.
• TypeScript equivalent under bun: the blocked object throws prompt blocked: {"blockReason":"SAFETY"}, the populated object logs the result, both in one run, exit 0.
• Generator negative paths, each confirmed to report against the offending spec, exit 1, and leave the rest of the run intact rather than throwing: an index segment in absent_when.path → bad absent_when path: index segments unsupported; a malformed segment → bad result path segment: [0]; a missing path or label → missing required key result.absent_when.<key>; a root-key collision → the new message below, reproduced in both the candidates[0]... and the result.sample path shapes.

Falsification of the deny path

This diff adds a raise SystemExit / throw dead-end, so its premise was checked against the provider rather than argued from our own docs. It does not deny a product capability — the success path is unchanged and was executed in both languages above — but the premise "blockReason set means there is no result to read" still had to be falsifiable, so I read Google's live spec, the same URL the CI job uses (https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta):

• GenerateContentResponse.properties is exactly [candidates, modelStatus, modelVersion, promptFeedback, responseId, usageMetadata], and the schema carries no required list — so a response omitting candidates is valid per the provider's own document, which is precisely the crash the snippets hit.
• promptFeedback → PromptFeedback, whose properties are [blockReason, safetyRatings].
• PromptFeedback.blockReason is documented verbatim as: "Optional. If set, the prompt was blocked and no candidates are returned. Rephrase the prompt." That is the guard's premise, stated by the provider.
• Its enum is [BLOCK_REASON_UNSPECIFIED, SAFETY, OTHER, BLOCKLIST, PROHIBITED_CONTENT, IMAGE_SAFETY], so the SAFETY value used in the sanity check above is a real one rather than an invented string.

The Output schema already rendered on these four pages says the same thing, and the specs' provider_spec.omit already lists promptFeedback.safetyRatings, which is independent evidence that CI has been walking into this object against the live document all along.

Judgment calls

• One deviation from the plan, and --validate would not have caught it. The plan specified the Python guard print {result[<JSON of first segment>]}, i.e. f"prompt blocked: {result["promptFeedback"]}". Reusing the enclosing double quote inside an f-string expression requires PEP 701, which landed in Python 3.12; on 3.11 and older it is a SyntaxError, which I confirmed directly — /usr/bin/python3 (3.9.6) rejects the plan's form with SyntaxError: f-string: unmatched '[' and accepts the shipped form. So the emitter uses a single-quoted key: f"prompt blocked: {result['promptFeedback']}". Runtime output is byte-identical and matches the plan's stated acceptance string exactly. Worth noting for whoever reads this next: --validate runs python3 -m py_compile with whatever python3 is on PATH, so on a 3.12+ runner it would have compiled the plan's form happily and shipped a snippet that is a syntax error for a reader on an older interpreter.
• Added beyond the plan (1): presence validation for absent_when.path and absent_when.label. The plan asked only for path validation, but a spec setting absent_when without a label would have shipped the literal string undefined: {...} into a snippet that still compiles.
• Added beyond the plan (2): a root-key collision check, in the second commit. This one closes a hole this diff itself opens, so it is not drive-by scope. Because the absent_when member is spliced in alongside the result member, an absent_when.path sharing result.path's root key emits type Result = { candidates?: {...}; candidates: {...} } — a duplicate identifier. I confirmed the whole failure chain rather than assuming it: the generator emitted that line, --validate exited 0 on it, and tsc 5.7 --strict on the emitted type reports TS2300: Duplicate identifier 'candidates' (plus TS2687 and TS2717). The reason CI misses it is structural — --validate transpiles TypeScript with bun build --no-bundle, which strips types without checking them, so it catches a syntax break but never a type break. A broken type would have shipped silently onto a public docs page. The check now reports it per-spec, exit 1, and no generated page changes.
• Added in review: label escaping at all four emission sites (pyEscape, pyFEscape, tsEscape, tsTemplateEscape). This reverses an earlier judgment call in this PR, which had left labels unescaped on the reasoning that a label breaking those literals is a syntax error, the class --validate genuinely does catch. That reasoning was tested and is wrong for three of the four sites: a { in the Python f-string compiles and then raises NameError at run time, and a backtick or ${ in the TypeScript template literal transpiles clean while altering or executing the emitted expression. Only the "-in-f-string case is the syntax error the old argument assumed. Silent breakage on a public docs page is worth escaping for, and escaping the pre-existing result.label sites too keeps the consistency the original call was protecting.
• Added in review: non-identifier path segments are quoted, not rejected. A provider field name need not be a TypeScript identifier (prompt-feedback is a legal JSON key), and dot access on one is not a syntax error: data.prompt-feedback?.blockReason transpiles to data.prompt - feedback?.blockReason, silently reading the wrong property, with only the emitted type member failing the build and pointing at the wrong cause. Rejecting such a segment was implemented first and then backed out — the Python emitters already supported the shape (pySafeGet/pyKeyLiteral quote every segment), so rejecting would have denied one language what the other already handled, and a spec author cannot rename a provider's field. tsAccess/tsKey now bracket and quote instead. result.path had the identical hole in tsPath/tsResultType and is fixed with the same helpers.
• Gating on blockReason means a hypothetical response carrying both candidates and promptFeedback.blockReason would exit before printing. Google's live spec (quoted above) states blockReason is set only when the prompt was blocked and no candidates are returned, so that state is not one the provider documents.

Origin thread: #1533 (comment)

Residual

• Nothing is verified against a live Router or Google generation call. Every behavioural check here is static: --validate syntax-checks the emitted snippets, and the blocked/unblocked behaviour was proven by substituting a hand-built response object for the SDK call, exactly as the plan specified. No snippet was executed against https://api.comfy.org/v2/models/..., nothing was billed, and no real safety block was triggered. The only live network read was Google's public discovery document. Verifying the guard against a genuinely blocked Router response is a separate, credentialed job this PR does not run.
• comfy_sdk / @comfyorg/sdk return shapes were not exercised. The Python guard assumes client.models.run(...) returns a plain dict supporting .get, and the TypeScript guard assumes comfy.models.run<Result>() resolves { data } as the provider's native JSON. Both assumptions are inherited unchanged from the existing emitters (the result[...] / data.... accessors already on these pages), but neither SDK was installed or called. If either wraps the response in an object without .get, the guard is wrong in the same way the surrounding snippet already is — and it would be wrong on all four pages at once.
• The generated TypeScript is never typechecked in CI, on this branch or before it. The collision check above closes the one type-level hole this diff introduces, but it is a targeted guard, not a general fix: --validate still transpiles rather than typechecks, so any other type-level defect in an emitted snippet — including in the five pages this PR does not touch — would still ship. Running tsc over the emitted TypeScript would close the class rather than the instance, and is worth its own change.
• Only the 2-segment absent_when path shape ships. 1- and 3-segment paths were exercised against the helpers directly and are correct, but no spec uses them and no generated page covers them, so nothing end-to-end covers those shapes. Index segments are rejected by design.
• The other providers were swept but deliberately not fixed — the numbers. All 9 code.yaml in tutorials/partner-nodes/** were checked for a documented empty-success shape. 4 (the Google specs) document promptFeedback.blockReason and now carry the guard. The remaining 5 — 4 BFL (flux-1-1-pro-ultra-image, flux-video-upscale, flux-3-video, flux-1-kontext) and 1 Ideogram (ideogram-v4) — document none and were left untouched per the plan, and their pages are byte-identical here. If either provider later gains a documented empty-success shape it needs its own absent_when and its own verification.
• The BFL rationale is unverified and rests on the plan's assertion, not on anything I read. The claim that Router converts BFL moderation to a non-2xx error before the body reaches the snippet names a middleware path in a different, non-public repository, which was not available in this environment and was not read (the path itself is omitted here deliberately, since this PR body is world-readable). If that conversion does not hold, the 4 BFL pages have the same latent crash the Google pages had, and this PR does not fix it.
• Unexercised artifacts: the upstream design discussion referenced by this work, and the related tracking issues named alongside it, were not reachable from this environment; their content was not read, so nothing here was validated against them beyond what is written above. CodeRabbit has since reviewed this PR (an earlier revision of this section said it had skipped the PR because the base is not the default branch; that is no longer true). It raised three findings: two were valid and are fixed above, and the third — make candidates optional in the generated type Result — was declined with evidence, because tsc 5.7 --strict reports TS18048: 'data.candidates' is possibly 'undefined' on that shape. The guard is a throw, not a narrowing, so making the member optional would force a ! or a redundant second check on every reader pasting the snippet into a strict project.
• This is a stacked PR (see the banner): it is verified against docs/router-model-page-pilot, not against main, and the generator it modifies does not exist on main. If docs(partner-nodes): generated Code pages for every Router-addressable partner model #1533 changes the emitters before it merges, this needs a rebase and a re-run of --check before it is trustworthy.

Provenance

• Authored by: agent-work loop
• Verified: gen-code-pages.ts --check --validate: 9 code pages fresh, 0 stale, 0 snippet syntax failures, exit 0; writing form re-run leaves a clean tree. check-provider-schemas.ts: 14 models, 0 skipped, 0 errors, exit 0. Regenerated nano-banana-2 Python snippet on Python 3.9.6 and 3.14.6: blocked response exits 1 with prompt blocked: {'blockReason': 'SAFETY'}, unblocked prints the result and exits 0; the pre-change snippet raises KeyError: 'candidates' on the same input. TypeScript equivalent under bun: throws with the reason, then logs the result, exit 0. Generator negative paths each reported per-spec with exit 1 and the run intact. tsc 5.7 --strict on the collision-shaped type Result: TS2300. Google's live v1beta discovery document read directly to confirm promptFeedback.blockReason and the absence of a required marker on candidates. Review round: the two label failure modes reproduced ({b} → NameError at run time, ${...} → transpiles and executes) and then confirmed fixed by round-tripping the label prompt {b} `x` ${y} "q" blocked verbatim through Python 3.9.6 and bun; a hyphenated absent_when.path confirmed to emit data["prompt-feedback"]?.["block-reason"] with a quoted type member, passing tsc 5.7 --strict --noEmit at exit 0, and a hyphenated result.path confirmed to emit quoted access in all three languages. All nine pages regenerate byte-identical after both fixes.
• Deviations: the Python guard emits a single-quoted key inside the f-string rather than the plan's double-quoted one, because the double-quoted form is a SyntaxError before Python 3.12 (confirmed on 3.9.6); runtime output is identical. Checks added beyond the plan: presence validation for absent_when.label, a root-key collision check, and — in the review round — label escaping at all four emission sites plus quoting of non-identifier path segments for both absent_when.path and result.path. The review round also reversed one of this PR's own earlier judgment calls (see Judgment calls) after testing its stated premise and finding it false. Everything else in the plan was implemented as written.